<p>在日历上能够让用户直观了解日常安排并进行规划。ZUI提供了实用简单的日历插件。</p>
<h3>实例</h3>
<p>在下面的示例中展示了按月展示的日程安排。点击日历上方的操作按钮切换月份，拖动日历中的事件到其他位置来重新安排时间。</p>
<p>按周或查看某一天的日程视图将在后续版本中到来。</p>
<div class="example calendar" id="calendarExample"></div>
<pre class="prettyprint">
<code>&lt;!-- HTML 代码 --&gt;
&lt;div id=&quot;calendar&quot; class=&quot;calendar&quot;&gt;&lt;/div&gt;
/* JS 代码 */
$(&#39;#calendar&#39;).calendar();
</code>
</pre>
<h3>使用方法</h3>
<h4>启动参数</h4>
<table class="table table-bordered">
  <thead>
    <tr>
      <th>参数</th>
      <th>值</th>
      <th>说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>startView</code></td>
      <td>
        <ul>
          <li><code>&quot;month&quot;</code> (默认)，月份视图</li>
        </ul>
      </td>
      <td>起始视图，默认为月份视图</td>
    </tr>
    <tr>
      <td><code>startDate</code></td>
      <td>
        <ul>
          <li><code>&quot;today&quot;</code> (默认)，其实日期为当天</li>
          <li><code>&quot;2014-8-14&quot;</code>，表示日期的字符串</li>
          <li>一个<code>Date</code>实例</li>
        </ul>
      </td>
      <td>起始视图所在的日期</td>
    </tr>
    <tr>
      <td><code>limitEventTitle</code></td>
      <td>
        <ul>
          <li><code>true</code> (默认)</li>
          <li><code>false</code></li>
        </ul>
      </td>
      <td>是否限制事件标题长度，如果为<code>true</code>则会限制事件标题在一行显示，超出部分将隐藏</td>
    </tr>
    <tr>
      <td><code>storage</code></td>
      <td>
        <ul>
          <li><code>true</code> (默认)</li>
          <li><code>false</code></li>
        </ul>
      </td>
      <td>
      是否启用本地存储来增强体验，如果为<code>ture</code>则会记录用户所在的视图和日期，刷新或关闭浏览器再次访问会重现最后的视图</td>
    </tr>
    <tr>
      <td><code>withHeader</code></td>
      <td>
        <ul>
          <li><code>true</code> (默认)</li>
          <li><code>false</code></li>
        </ul>
      </td>
      <td>是否显示带操作栏的头部，如果为<code>true</code>则会显示头部，包含切换视图或日期的按钮</td>
    </tr>
    <tr>
      <td><code>dragThenDrop</code></td>
      <td>
        <ul>
          <li><code>true</code> (默认)</li>
          <li><code>false</code></li>
        </ul>
      </td>
      <td>是否启用事件拖放功能，如果为<code>true</code>则能够拖拽一个事件到另一个日期方框内来更改事件日程</td>
    </tr>
    <tr>
      <td><code>lang</code></td>
      <td>
        <ul>
          <li><code>null</code> (默认)</li>
          <li><code>&quot;zh-cn&quot;</code></li>
        </ul>
      </td>
      <td>当前界面所使用的语言，如果留空则会从<code>html</code>标签上读取lang属性</td>
    </tr>
    <tr>
      <td><code>data</code></td>
      <td><code>{calendars: {}, events: []}</code></td>
      <td>初始加载的日历数据</td>
    </tr>
  </tbody>
</table>
<h4>方法</h4>
<p>日历插件提供一组方法来向日历添加新的时间、更改已有事件或者删除已有事件。</p>
<h5>获取日历对象实例</h5>
<p>
要使用日历对象方法，需要首先获取日历对象实例。每一个日历对象示例的引用都存储在对应的jQuery对象的data中，名称为<code>zui.calendar</code>。</p>
<pre class="prettyprint">
<code>/* 获取日历对象实例 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
</code>
</pre>
<h5>切换或刷新视图</h5>
<p>要切换不同的视图或所显示的日期范围，请使用日历对象的<code>display(view, date)</code>方法。</p>
<pre class="prettyprint">
<code>/* 切换视图或刷新视图 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
calendar.display(&#39;month&#39;, &#39;2014-8-14&#39;);   // 切换视图为月份视图，并将日期范围限定为2014年8月
calendar.display(&#39;month&#39;);                // 切换视图为月份视图，使用当前日期范围
calendar.display();                       // 重新刷新当前视图
</code>
</pre>
<h5>增加事件</h5>
<h6>增加一个事件</h6>
<p>将一个新的事件对象作为参数来调用<code>addEvents</code>方法。</p>
<pre class="prettyprint">
<code>/* 增加一个事件 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
var newEvent = {title: &#39;吃饭了&#39;, desc: &#39;要吃更多&#39;, start: &#39;2014-8-14 12:00&#39;, end: &#39;2014-8-14 13:00&#39;};
calendar.addEvents(newEvent);
</code>
</pre>
<h6>增加多个事件</h6>
<p>将包含一组事件的数组作为参数调用<code>addEvents</code>方法则可以一次性添加多个事件。</p>
<pre class="prettyprint">
<code>/* 增加多个事件 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
var newEvents =
[
  {title: &#39;吃饭了&#39;, desc: &#39;要吃更多&#39;, start: &#39;2014-8-14 12:00&#39;, end: &#39;2014-8-14 13:00&#39;},
  {title: &#39;学习了&#39;, desc: &#39;要学更多&#39;, start: &#39;2014-8-14 13:00&#39;, end: &#39;2014-8-14 17:00&#39;}
];
calendar.addEvents(newEvents);
</code>
</pre>
<h6>事件对象</h6>事件对象实例可以指定以下属性：
<table class="table table-bordered">
  <thead>
    <tr>
      <th>属性</th>
      <th>值</th>
      <th>说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>title</code></td>
      <td>字符串</td>
      <td>事件标题</td>
    </tr>
    <tr>
      <td><code>desc</code></td>
      <td>字符串， 可选</td>
      <td>事件描述</td>
    </tr>
    <tr>
      <td><code>allDay</code></td>
      <td>
        <ul>
          <li><code>true</code></li>
          <li><code>false</code> (默认)</li>
        </ul>
      </td>
      <td>是否为全天事件</td>
    </tr>
    <tr>
      <td><code>start</code></td>
      <td>
        <ul>
          <li><code>&quot;2014-8-14&quot;</code>，表示日期的字符串</li>
          <li>一个<code>Date</code>实例</li>
        </ul>
      </td>
      <td>事件开始的时间</td>
    </tr>
    <tr>
      <td><code>end</code></td>
      <td>
        <ul>
          <li><code>&quot;2014-8-14&quot;</code>，表示日期的字符串</li>
          <li>一个<code>Date</code>实例</li>
        </ul>
      </td>
      <td>事件结束的时间，如果<code>allDay</code>属性为<code>true</code>(即为全天事件)时该属性可选</td>
    </tr>
    <tr>
      <td><code>calendar</code></td>
      <td>字符串，可选</td>
      <td>事件所在的日历</td>
    </tr>
    <tr>
      <td><code>data</code></td>
      <td>任何值</td>
      <td>一个额外的属性用来存储其他与该事件关联的数据</td>
    </tr>
  </tbody>
</table>
<h5>移除事件</h5>
<p>
指定需要移除的事件的<code>id</code>属性，或者同时指定多个<code>id</code>并放在一个数组中作为参数来调用<code>removeEvents</code>方法。</p>
<pre class="prettyprint">
<code>/* 移除事件 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
calendar.removeEvents(&#39;4343&#39;);                   // 移除id为4343的事件
calendar.removeEvents([&#39;4343&#39;, &#39;4344&#39;, &#39;4345&#39;]); // 一次性移除多个事件
</code>
</pre>
<h5>更新事件</h5>
<h6>更新事件属性</h6>
<p>将更新对象或者由包含更新对象的数组作为参数来调用方法<code>updateEvents</code>。</p>
<pre class="prettyprint">
<code>/* 移除事件 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
calendar.updateEvents(    // 更新一个事件
{
    event: &#39;343&#39;, // 要更新的事件
    changes:
    [
       {
          change: &#39;title&#39;,          // 要更改的属性名称,
          to:     &#39;一个新的事件标题&#39;  // 更改后的值
       },
       {                            // 同时更改另一个属性
          change: &#39;start&#39;,          // 要更改的属性名称,
          to:     &#39;2014-8-15 9:00&#39;  // 更改后的值
       }
    ]
});
calendar.updateEvents(    // 一次性更新多个事件
[
    {
        event: &#39;343&#39;, // 更新第一个事件
        changes:
        [
           {
              change: &#39;title&#39;,          // 要更改的属性名称,
              to:     &#39;一个新的事件标题&#39;  // 更改后的值
           },
           {                            // 同时更改另一个属性
              change: &#39;start&#39;,          // 要更改的属性名称,
              to:     &#39;2014-8-15 9:00&#39;  // 更改后的值
           }
        ]
    },
    {
        event: &#39;344&#39;, // 更新另一个事件
        changes:
        [
            // ...
        ]
    },
]);
</code>
</pre>
<h5>增加日历</h5>
<h6>增加一个日历</h6>
<p>将一个新的日历对象作为参数来调用<code>addCalendars</code>方法。</p>
<pre class="prettyprint">
<code>/* 增加一个日历 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
var newCalendar = {name: &#39;work&#39;, title: &#39;工作&#39;, desc: &#39;这是一个工作日历&#39;, color: &#39;#ff0000&#39;};
calendar.addCalendars(newCalendar);
</code>
</pre>
<h6>增加多个日历</h6>
<p>将包含一组日历的数组作为参数调用<code>addCalendars</code>方法则可以一次性添加多个日历。</p>
<pre class="prettyprint">
<code>/* 增加多个日历 */
var calendar = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
var newCalendars =
[
  {name: &#39;work&#39;, title: &#39;工作&#39;, desc: &#39;这是一个工作日历&#39;, color: &#39;#ff0000&#39;},
  {name: &#39;home&#39;, title: &#39;家庭&#39;, desc: &#39;这是一个家庭日历&#39;, color: &#39;#00ff00&#39;}
];
calendar.addCalendars(newCalendars);
</code>
</pre>
<h6>日历对象</h6>日历对象实例可以指定以下属性：
<table class="table table-bordered">
  <thead>
    <tr>
      <th>属性</th>
      <th>值</th>
      <th>说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>name</code></td>
      <td>字符串，为全英文标识</td>
      <td>日历名称</td>
    </tr>
    <tr>
      <td><code>title</code></td>
      <td>字符串，可选</td>
      <td>日历标题</td>
    </tr>
    <tr>
      <td><code>desc</code></td>
      <td>字符串， 可选</td>
      <td>日历描述</td>
    </tr>
    <tr>
      <td><code>color</code></td>
      <td>表示十六进制颜色值的字符串，可选</td>
      <td>日历颜色</td>
    </tr>
  </tbody>
</table>
<h5>获取和同步数据</h5>
<p>当进行日历事件的添加、更新或者移除操作时注意同步数据。</p>
<p>你随时可以获取当前所有日历或事件的数据。</p>
<pre class="prettyprint">
<code>/* 获取日历数据 */
var calendar  = $(&#39;#calendar&#39;).data(&#39;zui.calendar&#39;);
var calendars = calendar.calendars; // 获取所有日历对象实例
var events    = calendar.events;    // 获取所有事件对象实例
</code>
</pre>
<p>当前获取了日历事件数据后可以手动直接更改所有属性，不过需要调用<code>display()</code>方法才能够将更改应用到界面中。</p>
<h4>事件</h4>
<p>日历中的事件既可以使用jQuery原生方法来绑定，也可以写在启动参数中。</p>
<table class="table table-bordered">
  <thead>
    <tr>
      <th>事件名称</th>
      <th>jQuery事件名称</th>
      <th>说明</th>
      <th>特别的事件参数</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>clickTodayBtn</code></td>
      <td><code>&quot;clickTodayBtn.zui.calendar&quot;</code></td>
      <td>点击日历头部的当天按钮时发生</td>
      <td>无</td>
    </tr>
    <tr>
      <td><code>clickNextBtn</code></td>
      <td><code>&quot;clickNextBtn.zui.calendar&quot;</code></td>
      <td>点击当前视图下一个日期范围按钮时发生</td>
      <td>无</td>
    </tr>
    <tr>
      <td><code>clickPrevBtn</code></td>
      <td><code>&quot;clickPrevBtn.zui.calendar&quot;</code></td>
      <td>点击当前视图上一个日期范围按钮时发生</td>
      <td>无</td>
    </tr>
    <tr>
      <td><code>clickEvent</code></td>
      <td><code>&quot;clickEvent.zui.calendar&quot;</code></td>
      <td>当点击一个事件时发生</td>
      <td>
        <ul>
          <li><code>event.event</code> 事件对象实例，当前点击的事件对象实例</li>
          <li><code>event.events</code> 事件对象实例数组，当前所有事件</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>beforeAddCalendars</code></td>
      <td><code>&quot;beforeAddCalendars.zui.calendar&quot;</code></td>
      <td>在向日历添加一个新的日历之前发生，如果在该事件处理函数中返回<code>false</code>，则会取消添加</td>
      <td>
        <ul>
          <li><code>event.newCalendar</code> 新的日历对象实例</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>addCalendars</code></td>
      <td><code>&quot;addCalendars.zui.calendar&quot;</code></td>
      <td>在向日历添加一个新的日历之后发生</td>
      <td>
        <ul>
          <li><code>event.newCalendars</code> 所有新的日历对象实例</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>beforeAddEvent</code></td>
      <td><code>&quot;beforeAddEvent.zui.calendar&quot;</code></td>
      <td>在向日历添加一个新的事件之前发生，如果在该事件处理函数中返回<code>false</code>，则会取消添加</td>
      <td>
        <ul>
          <li><code>event.newEvent</code> 新的事件对象实例</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>addEvents</code></td>
      <td><code>&quot;addEvents.zui.calendar&quot;</code></td>
      <td>在向日历添加一个或多个新的事件之后发生</td>
      <td>
        <ul>
          <li><code>event.newEvents</code> 所有新的事件对象实例</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>beforeRemoveEvent</code></td>
      <td><code>&quot;beforeRemoveEvent.zui.calendar&quot;</code></td>
      <td>在向日历移除一个事件之前发生，如果在该事件处理函数中返回<code>false</code>，则会取消移除</td>
      <td>
        <ul>
          <li><code>event.event</code> 需要移除的事件对象实例</li>
          <li><code>event.eventId</code> 需要移除的事件id</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>removeEvents</code></td>
      <td><code>&quot;removeEvents.zui.calendar&quot;</code></td>
      <td>在向日历移除一个或多个事件之后发生</td>
      <td>
        <ul>
          <li><code>event.removedEvents</code> 所有需要移除的事件对象实例</li>
          <li><code>event.data</code> 所有日历事件数据</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>beforeChange</code></td>
      <td><code>&quot;beforeChange.zui.calendar&quot;</code></td>
      <td>更改一个事件之前发生，如果在该事件处理函数中返回<code>false</code>，则会取消本次更改</td>
      <td>
        <ul>
          <li><code>event.event</code> 要更改的事件对象实例</li>
          <li><code>event.change</code> 要更改的属性名称</li>
          <li><code>event.from</code> 更改之前该属性的值</li>
          <li><code>event.to</code> 更改之后新的值</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>change</code></td>
      <td><code>&quot;change.zui.calendar&quot;</code></td>
      <td>当一个或多个事件发生更改时发生</td>
      <td>
        <ul>
          <li><code>event.data</code> 所有日历事件数据</li>
          <li>
            <code>event.changes</code> 数组，所有更改明细，每一项包含下列属性：
            <ul>
              <li><code>event.event</code> 要更改的事件对象实例</li>
              <li><code>event.change</code> 要更改的属性名称</li>
              <li><code>event.from</code> 更改之前该属性的值</li>
              <li><code>event.to</code> 更改之后新的值</li>
            </ul>
          </li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>beforeDisplay</code></td>
      <td><code>&quot;beforeDisplay.zui.calendar&quot;</code></td>
      <td>在重新显示视图之前发生，如果在该事件处理函数中返回<code>false</code>，则会取消显示</td>
      <td>
        <ul>
          <li><code>event.view</code> 字符串，要显示的视图名称</li>
          <li><code>event.date</code> 日期事件对象实例，要显示的日期</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>display</code></td>
      <td><code>&quot;display.zui.calendar&quot;</code></td>
      <td>在重新显示视图之后发生</td>
      <td>
        <ul>
          <li><code>event.view</code> 字符串，要显示的视图名称</li>
          <li><code>event.date</code> 日期事件对象实例，要显示的日期</li>
        </ul>
      </td>
    </tr>
    <tr>
      <td><code>clickCell</code></td>
      <td><code>&quot;clickCell.zui.calendar&quot;</code></td>
      <td>当点击一个日期单元格时发生</td>
      <td>
        <ul>
          <li><code>event.view</code> 字符串，当前视图名称</li>
          <li><code>event.date</code> 日期事件对象实例，当前单元格的日期</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>
<h5>使用启动参数处理事件</h5>
<pre class="prettyprint">
<code>$(&#39;calendar&#39;).calendar(
{
    clickEvent: function(event)
    {
        console.log(event);
        // console.log(&quot;你点击了一个事件&quot;);
        // 处理 clickEvent 事件
        // ...
    }
});</code>
</pre>
<h5>使用jQuery方法绑定事件处理函数</h5>
<pre class="prettyprint">
<code>$(&#39;calendar&#39;).calendar().on(&quot;clickEvent.zui.calendar&quot;, function(event)
{
    console.log(event);
    // console.log(&quot;你点击了一个事件&quot;);
    // 处理 clickEvent 事件
    // ...
});</code>
</pre>
